ATSUMeasureTextImage

OSStatus ATSUMeasureTextImage (
                     ATSUTextLayout iTextLayout,
                     UniCharArrayOffset iLineOffset,
                     UniCharCount iLineLength,
                     ATSUTextMeasurement iLocationX,
                     ATSUTextMeasurement iLocationY,
                     Rect *oTextImageRect);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iLineStart

A value of type UniCharArrayOffset. Pass the edge offset that corresponds to the beginning of the range of text whose standard bounding rectangle you want to obtain. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iLineLength parameter. If the offset is outside the text buffer, ATSUMeasureTextImage returns the result code kATSUInvalidTextRangeErr.

iLineLength

A value of type UniCharCount. Pass the length of the range of text whose standard bounding rectangle you want to obtain. To indicate the end of the text buffer, pass the constant kATSUToTextEnd, described in Text Length Constant. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iLineStart parameter. If the range of text is outside the text buffer, ATSUMeasureTextImage returns the result code kATSUInvalidTextRangeErr.

iLocationX

A value of type ATSUTextMeasurement. Pass the x-coordinate of the origin of the line (in the current graphics port) whose image bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the dimensions of the bounds relative to the current pen location in the current graphics port.

iLocationY

A value of type ATSUTextMeasurement. Pass the y-coordinate of the origin of the line (in the current graphics port) whose image bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the dimensions of the bounds relative to the current pen location in the current graphics port.

oTextImageRect

A pointer to a Rect. On return, the structure contains the dimensions of the enclosing rectangle representing the image bounds offset by the iLocationX and iLocationY parameters. If the line is rotated, the rectangle's sides are parallel to the coordinate axis. You cannot pass NULL for this parameter.

function result

A result code. The result code kATSUInvalidCacheErr indicates that an attempt was made to read in style data from an invalid cache (that is, the format of the cached data does not match that used by ATSUI or the cached data is corrupt). The result code kATSUQuickDrawTextErr indicates that the QuickDraw function DrawText encountered an error while measuring a line of text. For a list of other ATSUI-specific result codes, see Result Codes.

DISCUSSION

The ATSUMeasureTextImage function obtains the standard bounding rectangle, or image bounds, of a line of text. ATSUMeasureTextImage takes into account line rotation, alignment, and justification, as well as other characteristics that affect layout like hanging punctuation. The rectangle passed back in oTextImageRect is the same one used by the function ATSUDrawText to draw a line of text.

The standard bounding rectangle is the smallest rectangle that completely encloses the filled or framed parts of the line. While the typographic bounding rectangle takes into account the ascent and descent lines for the displayed glyphs, the standard bounding rectangle just encloses the "inked parts" of the displayed glyphs.

To obtain the typographic bounds of a line after it is laid out, call the function ATSUGetGlyphBounds. To calculate the typographic bounds of a line before it is laid out, call the function ATSUMeasureText.

If you want to instead obtain the typographic bounds of a final laid-out line, call the function ATSUGetGlyphBounds. To calculate the standard bounding rectangle around a final laid-out line, call the function ATSUMeasureTextImage. For an illustration of the difference between a standard and typographic bounding rectangle, see Figure 2-1.

Before calculating the standard bounding rectangle enclosing a range of text, ATSUMeasureTextImage examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUMeasureTextImage assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUMeasureTextImage assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUMeasureTextImage assigns the remaining characters to the last style run it can find.

The height of the standard bounding rectangle is determined by the natural line ascent and descent calculated for the line. ATSUMeasureTextImage ignores the previously set line ascent and descent values for the line it is measuring. However, it uses other text layout attributes set for the line determine character layout. If no attributes have been set for the line, ATSUMeasureTextImage uses attributes set for the text layout object.

If the line is rotated, the sides of the passed back rectangle are parallel to the coordinate axes and encompass the rotated line. You should pass the standard bounding rectangle of a line of text to the function EraseRect to ensure erase all the text. In contrast, the typographic bounding rectangle passed back by ATSUMeasureText reflects an unrotated line.

The coordinates you specify in iLocationX and iLocationY are the same values used by ATSUDrawText for the line of text to be measured.

SPECIAL CONSIDERATIONS

ATSUMeasureTextImage may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.

VERSION NOTES

Available beginning with ATSUI 1.0.